This chapter covers the development of an application which collects signup data through a form, available for later export by admins.
The walkthrough builds on Chapter 3 - it assumes you are familiar with feature blocks and using their built-in javascript helper functions.
After completing this chapter you'll be able to add complex sign up forms to your applications.
Oceanic Golden Ticket Sweepstakes
Oceanic Golden Ticket Sweepstakes is an example of using a signup form to collect entries for a sweepstakes. One lucky fan on Facebook will be chosen at random for free lifetime travel on Oceanic Airlines. All they have to do is provide their name, e-mail and phone number. Let's get started!
- In your SML application, paste in the following code:
<h3>Golden Ticket Sweepstakes</h3> <p>Enter your info below for a chance to win free lifetime travel on Oceanic Air!</p> {% signup_form %} <div><label for="name">Name:</label> <input type="text" name="name"id="name"> </div> <div><label for="email">Email:</label> <input type="text" name="email" id="email"> </div> <div><label for="phone_no">Phone Number:</label> <input type="text" name="phone_no" id="phone_no"> </div> {% signup_form_submit %} {% endsignup_form %}
- Click "Save Changes". You should now see a new row in the Features table for a "default" signup_form.
- Click "Configure" under Actions for the signup_form Feature Block settings.
- Click "Save Settings" - no configuration is required.
- Click "Return to Facebook Page". You should see a form similar to the one shown below.
- In the form, fill in a name, e-mail and phone number and then click "Submit".
- With just a few lines of markup we now have a fully functioning signup form! Lets take a minute to break down the code...
First you'll notice a new Feature Block, signup_form. This feature allows you to easily collect information from users through a form. The data is collected, hosted and available for export at any time by an administrator. More on this export functionality later.
You'll also notice there was no configuration step required. The signup form is a simple HTML form. Fields are defined as HTML form fields - text inputs in our example - and a special {% signup_form_submit %} tag generates the form's submit button. No configuration is required.
Adding a Custom Success Message
By default, a standard message is displayed after a user successfully submits their information (shown above). You can customize this success behavior easily. Lets change our application to instead show a message which asks users to come back at a later date to see if they are the lucky winner.
- Change your code to now read:
{% signup_form onsuccess:"showThankYouMessage();" %} <div><label for="name">Name:</label> <input type="text" name="name" /> </div> <div><label for="email">Email:</label> <input type="text" name="email" /> </div> <div><label for="phone_no">Phone Number:</label> <input type="text" name="phone_no" /> </div> {% signup_form_submit %} {% endsignup_form %} <div id="thank_you_message" style="display:none"> <h2>Thanks for entering! Check back here December 1st to see if you've won.</h2> </div> <script type="text/javascript"> function showThankYouMessage() { sml.get('signup_div').hide(); sml.get('thank_you_message').show(); } </script>
- Click "Saves Changes" and "Return to Facebook Page". You should now see your custom success message.
- Lets talk about the new code...
The signup_form Feature Block, like most other Feature Blocks, has attributes you can customize. Here we pass a custom javascript function for it's onsuccess attribute. This is a callback the form makes whenever a form is successfully submitted.
Our custom javascript function – showThankYouMessage() – uses the SML Javascript API to hide the signup form and show a hidden div we added which contains our customized thank you message.
Adding Validation
A common concern when dealing with forms is ensuring valid user input. Some fields may be mandatory while others must match valid formats. In our Sweepstakes, for example, we probably want to ensure that all fields are filled out by the user & that we are collecting valid e-mail addresses.
- Lets add some validations to our form.
- Update your code to now read:
{% signup_form onsuccess:"showThankYouMessage();" rules_var:"sweeprules" %}
<div><label for="name">Name:</label>
<input type="text" name="name"/>
</div>
<div><label for="email">Email:</label>
<input type="text" name="email"/>
</div>
<div><label for="phone_no">Phone Number:</label>
<input type="text" name="phone_no"/>
</div>
{% signup_form_submit %}
{% endsignup_form %}
<div id="thank_you_message" style="display:none">
<h2>Thanks for entering! Check back here December 1st to see if you've won.</h2>
</div>
<script type="text/javascript">
var sweeprules = {
email: {
required: true,
email: true
},
name: {
required: true
},
phone_no: {
required: true
}
}
function showThankYouMessage() {
sml.get('signup_div').hide();
sml.get('thank_you_message').show();
}
</script>
- Click "Saves Changes" and "Return to Facebook Page". Now try submitting the form without all fields filled in or without a properly formatted email address. You should be prompted with an error message.
- How did the signup_form know to validate the form per our validation logic? To understand this, lets look closer at our changes...
We added a new javascript variable to our template called sweepRules. This object is a simple javascript hash. For each field in our form, we have a corresponding property in the hash. Each property then declares if it is required or needs to be validated.
The signup_form Feature Block has an additional attribute which takes the name of a variable with the same structure as our sweepsVar. When the form is submitted, the feature block validates the fields against this special javascript rules variable.
Validation in SML signup forms is simple yet very powerful - you can choose from several built-in validations or define your own custom validation logic by declaring your validations in a javascript variable.
Adding Fan Gating
Entering a sweepstakes for free lifetime travel is an amazing offer. Wouldn't it be great if we could only allow fans of the page to enter the sweepstakes?
- Lets add a fan gate to our form.
- Update your code to now read:
{% if is_page_fan %} {% signup_form onsuccess:"showThankYouMessage();" rules_var:"sweeprules" %} <div><label for="">Name:</label> <input type="text" name="name"/> </div> <div><label for="">Email:</label> <input type="text" name="email"/> </div> <div><label for="">Phone Number:</label> <input type="text" name="phone_no"/> </div> {% signup_form_submit %} {% endsignup_form %} <div id="thank_you_message" style="display:none"> <h2>Thanks for entering! Check back here December 1st to see if you've won.</h2> </div> <script type="text/javascript"> var sweeprules = { email: { required: true, email: true }, name: { required: true }, phone_no: { required: true } } function showThankYouMessage() { sml.get('signup_div').hide(); sml.get('thank_you_message').show(); } </script> {% else %} <h2>Become a fan to enter our sweepstakes for free lifetime travel!</h2> {% endif %} - Click "Saves Changes" and "Return to Facebook Page". If you are not a fan of your page, you should see a message telling you to become a fan. Upon clicking Facebook's "Like" button, the application should refresh and you should see the signup form.
- Lets break down how we added the fan gate...
is_page_fan is a Global Context Variable which is true if the user is a fan, false if they are not. We combine this variable with the {% if %} and {% else %} tags to show two different experiences - one for fans, the other for non-fans.
Fan Gating is a popular technique used in social applications to drive fan growth and reengagement by incentivizing access to exclusive content. Using the is_page_fan Global Context Variable with the {% if %} tag gives you the option to easily fan gate anything in your application.
Configuring Export
Our system will save all submitted form data forever - until and unless you use the link in your configuration window to manually delete it. You can export signup data directly from the settings page. For each input that you wish to export, you'll need to add a reporting field under the reporting section. Fields can be added and removed from this section at any time - changes only affect which fields are displayed in the report.
Your export experience may look slightly different than the one below
Once your reporting fields have been configured, you can export collected signups by clicking the download signups link at any point.
Configuring Email Notifications
Along with self-serve export, you can also configure your form to notify any email address whenever a new signup is collected. A common use case for email notifications is simple integration with third-party systems. Any system that can receive mail can integrate with your signup form!
Here is an example of the email:
The campaign owner for <Campaign> SML (CampaignID: 169662), <User> (UserID: 1234567), has sent a new signup feature notification. Params: feature_id = 654321 page_id = 16248095488 email = hi@hi.com
Next Steps
You've now built an application that collects signup data through a fan gate. Take a look at the links below to read more about the signup form feature block. Add new fields and validations to your form. Experiment with different post-signup behavior. Can you think of other opportunities where fan gating would be a good fit?
On to Chapter 5
20101013-sq4daxyjyy1sfunqdnn1cfqcn.jpg (image/jpeg)
20101014-j55ib7sr32hxegmuaxywid75u6.jpg (image/jpeg)
reporting_fields.jpg (image/jpeg)
20101013-c916jksrk68e6iyxubc7x7t86p.jpg (image/jpeg)
